Monitoring API for the Robotic Automation Solution

The Real-Time Server exposes an API for querying the state and status of the following queries:

The number and rate of automation invocation requests

The queue sizes

The state of the robot farm instances

This monitoring API applies to async invocations, sync invocations (conversation) and scheduled tasks.

This API uses HTTP/JSON, whereby the client communicates with the agent over HTTP (GET or POST) with the request and response payload represented in JSON. The protocol used in the API is based on Representational State Transfer (REST), which relies on a stateless, client-server, cache-suitable communications protocol, and, in virtually all cases, uses an HTTP protocol. The examples found in this section are all examples of REST responses or requests.

Monitoring API Format

Use the following API format for queries.

GET Exec Request

The format of a GET Exec request is:

<base url>/exec/<mbean name>/<operation name>/<arg1>/<arg2>/....

The following table describes each part of the request and provides an example:

Part	Description	Example
<base url>	The base for the URL	http://<server IP>:8778/Jolokia
<mbean name>	This is the MBean's ObjectName	RA:name=RAFailedRequestsJmx
<operation name>	Name of the operation to execute. Shall include a method signature. A signature is the fully qualified argument class names or native types, separated by columns and enclosed with parentheses.	getFailedRequestsPercentage(int,short,short,int)
<arg1>, <arg2>,	String representation for the arguments required to execute this operation. The order of the arguments must match the API.	"true","true",1

GET Search Request

The format of the search GET URL is:

<base-url>/search/<pattern>

This mode is used to query for certain MBeans, and uses a single argument pattern for specifying the search parameter such as in:

The pattern can contain wildcards such as * and ?. The Mbean names that match the query are returned as a list within the response.

Exec Response

Responses are always encoded in UTF-8 JSON. If no error occurred, a JSON response looks the same for each request type except for the value attribute, which is request type-specific.

For successful requests, the status is always 200 (the HTTP success code). The timestamp contains the ‘seconds since 1.1.1970’ time when the request was handled. The request to this response can be found under the attribute request.

For an exec operation, the response contains the return value of the operation. A typical response for a URL, such as:

Is as follows:

If an error occurs, the status will be a number other than 200, and the error response will be as follows:

Get READ Request

The format of the GET READ Request uses the following URL format:

<base-url>/read/<mbean name>/<attribute name>/<inner path>

An inner path within the format points to a certain substructure within a complex JSON value.

 

The attribute HeapMemoryUsage of the MBean java.lang:type=Memory can be requested with the following URL:

This returns a complex JSON structure such as:

In order to get to the value for the used heap memory, you will need to specify the inner path that was used. Therefore, the request:

will result in a response of 15348352.

Failed Requests Retrieval

The format of the GET Exec request to retrieve failed requests is as follows:

http://<Real-Time Server IP or Host Name>:8778/jolokia/exec/ RA:name=RAFailedRequestsJmx/getFailedRequestsPercentage(int,short,short,int)/timeFrameSec/errorTypeId/subErrorTypeId/executionStatus

 

Ordered Parameters for Retrieving Failed Requests

Make sure all the parameters are provided in the order described in the table. All parameters are mandatory.

Argument	Description	Applicable Values
(int) timeFrameSec	The time frame (in seconds) by which to filter requests.	Up to 604800 sec (7 days). For example last 24 hours: 86400 Negative and out of range values, default to 24 hours
(short) errorTypeId	Error code id	No filter -1 (or other negative) System Error 1 Robot Error 2
(short) subErrorTypeId	Sub error code id	No filter -1 (or other negative) Orphan 1 Backlog 2
(int) executionStatus	Work flow business execution status	No filter -1 (or other negative) Successful business execution 1 Failed business execution 0

Robot Status

The format of the READ request to obtain the robot status is as follows:

http://<Real-Time Server IP or Host Name>:8778/jolokia/read/ RA:name=RAGetRobotsStatusJmx/RobotsStatus

When using this format, no parameters are required, and all robot statuses are retrieved.

Robot historical status data is maintained for a period of the last seven days. A robot that is inactive for a long time will remain in the robot status list for seven days from the time it last reported a status and will then be removed.

The format of the response is: Where the response value is composed from a list of robot status structures, each containing three parameters:

Status ID

Status Name

Robot Machine Name

Unhandled Requests

This API is used to monitor requests that are about to become past due, and to monitor backlog growth.

Get the total number of unhandled requests

This request returns the total number of requests that have not been handled by any robot. The format of the READ request is:

http://<Real-Time Server IP or Host Name>:8778/jolokia/read/ RA:name=RAInProcessManagerJmx/TotalUnhandledInvokerRequests

Get the number of unhandled requests about to get expired, pending processing in the next X minutes

This request is used for monitoring requests that were not pulled by any robot and are about to expire in the next X minutes (where X is a parameter).

Some types of requests should be processed within 24 hours. If a request remains in a status of "in process" and the defined threshold is 21 hours, this may result in a large number of anticipated failures (backlog errors), The IT department can, therefore, instruct the customer not to invoke or to reduce the number of invocations in order to reinitialize the backlogged requests.

The format of the EXEC request is:

http://<Real-Time Server IP or Host Name>:8778/jolokia/exec/ RA:name=RAInProcessManagerJmx/ getTotalBackloggedInvokerRequests(int)/currentTimeOffsetInMinutes

currentTimeOffsetInMinutes: The offset in minutes, relative to the current time, by which to filter unhandled requests.

:

Get the oldest request unhandled period in minutes

 

This request returns the number of minutes of the oldest request that was not pulled by a robot. The format of the READ request is:

http://<Real-Time Server IP or Host Name>:8778/jolokia/read/ RA:name=RAInProcessManagerJmx/OldestInvokerRequestPendingTimeInMinutes

Successful Requests

Average Successful Robot Handling Time

This parameter returns the average robot processing time of requests in seconds, in the last specified time frame in seconds:

http://<Real-Time Server IP or Host Name>:8778/jolokia/exec/RA:name=RASuccessfulRequestsJmx/getAvgSuccessfulHandlingTime(int)/timeFrameSec

 

timeFrameSec: The time frame (in seconds) by which to filter requests. Requests are saved in UTC time and are then filtered according to the database server's current UTC time minus the timeFrameSec.

Successful Automation Request Amounts

This parameter returns the amount of successful requests in the last specified time frame in seconds.

http://<Real-Time Server IP or Host Name>:8778/jolokia/exec/RA:name=RASuccessfulRequestsJmx/getNumSuccessfulRequests(int)/ timeFrameSec

 

timeFrameSec: The time frame (in seconds) by which to filter requests. Requests are saved in UTC time and are then filtered according to the database server's current UTC time minus the timeFrameSec.

ActiveMQ Queue Size

In order to receive a Real-Time Server's queue size via REST, invoke an HTTP GET request with the following URL, replacing the {RT server's IP} and {Queue's name} with the appropriate values:

http://<RTserverIP>:8161/api/jolokia/read/org.apache.activemq:type=Broker,brokerName=localhost,destinationType=Queue,destinationName={Queue's name}/QueueSize

If you are not sure of the correct queue name, go to http://<RTserverIP>:8161/admin/queues.jsp to see the full list of queues and copy the correct queue name from there.